Celestin Apprentice 4

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / C / Code Resources / Jims CDEFs 1.50 / Documents / About CDEFs < prev next >

Wrap

Text File | 1995-10-30 | 55.9 KB | 1,385 lines | [TEXT/KAHL]

Jim's CDEFs - Copyright © 1994-1995 by James G. Stout -------------------------------------------------------------------------------- About Jims CDEFs… If you have downloaded previous versions of this package, please read the "Version history" file, some minor but important details have changed !! Also, please read the license agreement in the "Conditions for use…" document included with the package. This is a collection of 11 CDEFs (Control Definitions) some bits of source code to demo their use AND the source code for all of the CDEFs. (If you are new to Mac programming, CDEFs are code resources that can just be pasted into your project's resource file and used by your programs). Jim Stout June 1995 I can be reached electronically at: Internet : JimS@WRQ.COM (work hours, PST) AppleLink : WRQ (daily) CompuServe : 73240,2052 (weekly or so) AOL : JasG (weekly or so) eWorld : Jim Stout (weekly or so) -------------------------------------------------------------------------------- The CDEFs or other code in this package may be incorporated in any freeware, shareware, commercial or other software package, subject to the conditions in the "License for Use" that accompanies this package. -------------------------------------------------------------------------------- The CDEFs in this package are: procID Name Function ------ ----------- -------------------------------------------------------- 0 3D√ Buttons as 1107, but with a "real" check mark for checkBoxes 1100 GroupBox Titled box, text in upperleft 1101 PopUp Menu System 7 style popup menu control for System 6 or 7 1102 Spinner A "little arrows" control 1103 Date & Time Date & Time control using "little arrows" 1104 Tog Button New type of "one or many" control 1105 HSlider Horizontal slider control 1106 VSlider Vertical slider control 1107 3D Buttons 3d replacement for the standard button CDEF 1108 Progress Bar A "thermometer" or "barber pole" progress indicator 1109 TabPanel A "Tab Panel" control as in MSWord 1110 Slider A vert or horiz slider. 1111 3D Buttons-rect A rectangular version of the 3D Buttons CDEF -------------------------------------------------------------------------------- The source code for all of the CDEFs is included in the "CDEF Source" folder. Also included are Think, Symantec, CodeWarrior projects and MPW makefiles required to build the CDEFs. A set of standard #defines for variation codes etc. is provided in file "jimsCDEF.h". Also included is source for utility routines common to all of the CDEFs. A test harness to allow source level debugging is also included. Rather than take up the room for 11 test projects and code, there is only one - for the 3D Button CDEF. Test projects for the other 10 is left to the reader as a programming exercise. -------------------------------------------------------------------------------- This file is getting pretty long, it is divided into the following sections: - Introduction - Control Descriptions CDEF details - Variation codes & control size - Non-standard control RefCon usage - Non-standard control template usage General information - Using custom controls in a dialog - Using custom controls in a window - Colorizing Controls & Dialogs - Changing the font in a Dialog - Special popup menu notes - About "TogButtons" - About Tab Panels - Revision history -------------------------------------------------------------------------------- Introduction ============ In early 1994, I was reading the Human Interface volume of Inside Mac and it struck me as funny that Apple refers to various controls (used throughout the MacOS) as "not supported by the Toolbox". Controls like "little arrow" controls used to set Date & Time, Memory etc., "Slider Controls" like those in the Sound or Brightness control panels and a "Progress Bar" are simply are not to be found in the Toolbox. Apple simulates controls by displaying appropriate PICT's and handling mouse events in a dialog filter (I think). I realized that over the past couple of years, I had written some of those controls (the rest are hot off my coding pad). Two of the CDEFs, 1104 "Tog Button" and 1109 "TabPanel" are a little different. This is explained below in the sections "About Tog Buttons" and "About Tab Panels. All of these controls will work with System 6 or System 7 - the only caveats are: - PopUpMenu control requires PopUpMenuSelect. - TabPanel control requires AppendDITL etc. (System 6 with CTB or System 7) - 32bit ColorQuickdraw v1.2 is required for any of the controls to draw "3D" variants and to use the System 7 style gray when disabled. I have tested them on machines from a MacPlus through a Power Mac 8100. (Actually, I've tested these as far back as System 3.2 - I've gotta do something with that original 128k Mac with MacPlus ROM's that is sitting in the corner...) All controls with titles honor the "useWindFont" variation code (to draw in a non-System font) and if possible, the controls will honor control colors found in 'cctb' resources. The "3D Buttons" and "TabPanel" CDEFs will always use a "3D" effect if the background color is non-white AND the control can draw itself in color. This behavior cannot be overridden for these controls. Sorry. As far as I can tell, the controls all handle low memory situations by refusing to draw themselves. Let me know if you see any problems. I have not written these to support non-roman script systems. Other variation codes, sizes and non-standard control template values are listed below. -------------------------------------------------------------------------------- Control Descriptions ==================== Common features: - color per 'cctb' resources. - disable with "GrayishTextOr" effect under System 7. - have an embossed, 3D variation. - respect the "useWindFont" variation code (8). - All control drawing is clipped to the control rect, so it should be pretty obvious if you have a control rect that is too small. NOTE: all of these controls rely on a private data structure stored in the contrlData field of the control structure. Don't use this field for your own use or unpredictable things will happen. Also, some of the controls look at the value of the refCon when initializing to get some extra parameters. If you want to place a value in the refCon for your program's use, don't set it until AFTER you call NewControl or NewDialog and the controls have been initialized. (The DateTime CDEF is a MAJOR exception - see below - it uses the refCon for its "value" field.) -------------------------------------------------------------------------------- GroupBox This control is pretty simple. It frames the control rect and places the title in the upper left corner. It can be used to logically group a series of related controls. It does not respond to mouse clicks, it does have variation codes for a dashed-line frame and a 3D effect. To use this control, you have to play some games with the control rect to keep it from overlaying other controls. Essentially, you must set the control rect height to include ONLY the title and then specify the true height of the control in the contrlMax field. In response to an update event, you will need to call DrawControls or Draw1Control for this control. UpdtControls WILL NOT WORK !!!! -------------------------------------------------------------------------------- PopUp Menu This control was written to replace both the System 6 & 7 versions of the Apple CDEF 63. Apple's CDEF has some problems - it behaves differently under System 6 and System 7. The System 6 version does not honor menus with icons, requires a special variation code for color menus and has problems with menus narrower than the control rect (when using the popupFixedWidth variation code). The System 7 version does not draw colored menus at all. Neither version will work with a dynamically created menu. You should be able to use this CDEF with the same parameters as the Apple CDEF. There are several enhancements explained in the section on Non-standard control template usage and in the "Special popup menu notes" section. The handle stored in the contrlData field is as documented by Apple and can be used to retrieve the MenuHandle of the popup menu. See IM VI and the jimsCDEF.h file. -------------------------------------------------------------------------------- Spinner This a control that "Apple never wrote". It allows for adjustment of a numeric value via "little" arrows. The arrows can be vertical or horizontal. The default increment is 1, but this can be specified in the control template in the refCon field. The control value will increment in a "ballistic" manner - as the mouse button is held down, the increment value will increase from 1 to 10 to 100 to 1000. This CDEF can be "linked" to a dialog edit text item to update. CDEFs cannot get keyDown events, so the trick here is to have the CDEF update the edit text item. To do this, set the HiWord of control refCon to a DITL editText item number to be updated. In this case, set the LoWord of the refCon to the desired increment. The calling program must take care of insuring that only digits are typed into the edit text. ALSO, when the user types new digits, the calling program must get the contents of the edit item, convert it to a number and call SetCtlValue to let the control know about the new value. Otherwise, the next click in the control will wipe out the typed value. The handle stored in the contrlData field is documented in the jimsCDEF.h file. There is a "userData" field for your use. PartCodes returned via TrackControl are : 2 - in up arrow 3 - in down arrow (the control will have updated its value when TrackControl returns) -------------------------------------------------------------------------------- Date & Time This is a control to adjust Date and/or Time values. Clicking on a time or date component (month, hours, etc.) will highlight those digits and show "little" arrows that can be used to adjust the date or time value. Variation codes can specify display of Date, Time, both, horizontal or vertical display. The m/d/y order of the date will match what the user has set in the Date & Time control panel. Leading zeros are always drawn - it makes things a lot simpler for the CDEF. Likewise, 12 or 24 hour time is taken from the system settings. To force a 24 hour setting, pass a non-zero contrlMax in the control template. To get a "3D" effect for the control title and arrows, pass a non-zero contrlMin in the control template. The "value" of the control is a DateTimeRec. Since this is a long, it is stored in the contrlRfCon field, NOT in the contrlValue field of the control record. So, rather than using GetCtlValue(), use GetCRefCon() to access the control value. There is no keyboard handling for setting date & time. CDEFs do not have any mechanism for keyboard events. I think that this could be done from a user program, but I'll leave that as an exercise for those that need it. (Hint, the contrlValue is always the highlighted digits field and you can change the date & time shown by the control by setting a new DateTimeRec into the control RefCon and drawing the control.) Resetting the date and time requires the following: GetDateTime(&secs); SetCRefCon(hCtrl, secs); InvalRect(&(**hCtrl).contrlRect); -------------------------------------------------------------------------------- Tog Button This is explained in great detail below. A "Tog" button is a diamond shaped control, a mix of CheckBox and Radio button behavior. A group of these controls can have many "on" members (like a checkbox), but must always have one member that is "on" (like a radio button). This file requires use of some support routines in TogLib.c that must be called by your program. Variation code 4 in the 3D Buttons control will have the same result. -------------------------------------------------------------------------------- HSlider This is an exact duplicate of the slider control in the Brightness Control Panel. Several variation codes are available to alter the appearance of the control. See below or the demo program. This and the VSlider control will call back to an "actionProc" if one is set via SetCtlAction() and you call TrackControl with -1 as the last parameter. This could be used to implement a "live" display of the control value as the thumb is dragged around. Part codes returned to TrackControl are : 1 - in "thumb" 2 - in "decrease" 3 - in "increase" The control is drawn using internal bitmap data and cannot be easily customized. -------------------------------------------------------------------------------- VSlider This is an exact duplicate of the slider control in the Sound Control Panel. Several variation codes are available to alter the appearance and behavior of the control. See below or the demo program. See notes above for "actionProc" & TrackControl issues. The control is drawn using internal bitmap data and cannot be easily customized. -------------------------------------------------------------------------------- Slider This is yet another variation on a slider control. It will orient itself vertically or horizontally based on the control rect. This slider does not use internal bitmaps for its drawing, so you can easily modify its appearance by making changes to the drawing routine. See notes above for "actionProc" & TrackControl issues. -------------------------------------------------------------------------------- 3D Buttons This provides 3D equivalent to the standard push button, radio button and check box controls. An addition is variation code 4 - in this control it forces the push button to be the same color as as the window background, ignoring any 'cctb' resources. #defines in file cdef3D.c allow you to create a square edged version, a version that is always gray or a version with a "real checkbox". -------------------------------------------------------------------------------- Progress Bar This is a control to provide a "thermometer" or "barber pole" indicator. It can be used to display the progress of a long running operation (like the thermometer in the "Copying file…" alert. The "barber pole" variation can be used when the operation is proceeding, but the end point is not known - like searching for a series of files. Variation codes can be used for horizontal, vertical, rectangular, oval or barber pole indicators. -------------------------------------------------------------------------------- TabPanel This too, is explained in great detail below. This is a problematic control. It will be too "Windows-like" for many. I wrote it to see if it could be done on the Mac after seeing what a co-worker was doing. Don't use it if you don't like it. It draws a box with a series of "tabs" long the top edge, like At Ease in some respects. It could be used to provide a dialog with multiple "panels" - like the Think Project Manager "Options" dialog which uses a popup to switch panels, or many CommToolbox tools which use a list of icons. By default, there are 4 tabs per row with a maximum of 5 rows of tabs. This can be changed to get between 2 and 8 tabs/row. Clicking on a "tab" will change the control value. Your program can then change the other controls on the panel - either by hiding/showing controls or using ShortenDITL/AppendDITL calls. To use this control, you have to play some games with the control rect to keep it from overlaying other controls. Essentially, you must set the control rect height to include ONLY the tab titles and then specify the true height of the control in the contrlMin field. In response to an update event, you will need to call DrawControls or Draw1Control for this control. UpdtControls WILL NOT WORK !!!! -------------------------------------------------------------------------------- CDEF details -------------------------------------------------------------------------------- See file jimsCDEF.h for #defines for variation codes and structs for private data for Spinner & Popup menu CDEFs. Variation codes & control size ============================== (min h & w is minimum required height & width for the control rect when using Chicago 12 font) CDEF varCode min h & w Result --------- ---------- ---------- -------------------------------------------- GroupBox 0 16 x nn Draws a solid frame 1 Draws a dotted frame 2 3D effect on non-white backgrounds 4 an "inset box" effect on non-white backgrounds 8 Use the Window font for title NOTE: To avoid problems with "layering" of this control over or under the contents of a box, set the height of this control to 16 or so, then put the height you REALLY want in the contrlMax field of the CNTL template. The control rect (used by the Dialog Manager) will not obstruct other controls. However, when the control draws - it will use the height value from the contrlMax field. Uses cFrameColor & cTextColor from 'cctb' -------------------------------------------------------------------------------- PopUp Menu 19 x nn (see IM VI or Docs for Apple CDEF 63 19 x 25 for "triangle only" menu 1 use fixed width for menu 2 3D effect 4 use refCon for AddResMenu 8 Use the Window font for title & menu NOTE: if the menu has styled text items, the height may need to be greater than 19. It will need to be enlarged to if you have icons on the menu - make the height equal icon height + 5. Unlike the Apple CDEF 63, this control will: - behave the same with System 6 & 7 - properly handle colored menus There are several enhancements, see below. Uses cTextColor for title and colors from 'mctb' for menu. -------------------------------------------------------------------------------- Spinner 0 20 x nn Small, as in "Date & Time" Control panel 1 27 x nn Large, as in "Memory" Control panel 2 3D arrows 4 Horizontal arrows 8 Use the Window font for drawing NOTE: use 20 x 13 or 27 x 17 to get arrows only. 3D arrows are colored, as are system scroll bars, with with cTingeLight & cTingeDark. -------------------------------------------------------------------------------- Date & Time 0 20 x 160 Date left, Time right justified 1 20 x 80 Date only, left justified 2 20 x 80 Time only, left justified 4 37 x 80 Both on 2 lines, date over time 8 Use the Window font for drawing NOTE: non-standard date or time separator characters may need a larger rect. Also, if a title is specified, the width of the control will need to be increased. Uses cFrameColor & cTextColor. 3D arrows colored with cTingeLight & cTingeDark. -------------------------------------------------------------------------------- Tog Button 0 18 x nn Normal button title 1 * not used * 2 * not used * 4 * not used * 8 Use the Window font for title Uses cFrameColor & cTextColor from 'cctb' -------------------------------------------------------------------------------- HSlider 0 24 x 121 As in the "Brightness" Control panel 1 Scale drawn in white (not filled) 2 Drawn with a 3D effect 4 Scale drawn in gray pattern 8 * not used * Uses cFrameColor, cBodyColor, cThumbColor & cTextColor from 'cctb' -------------------------------------------------------------------------------- VSlider 0 105 x 42 As in the "Sound" Control panel 1 Scale drawn in white (not filled) 2 Drawn with a 3D effect 4 "Thumb" will not "snap" to tick mark 8 Scale is blank, no numbers, no marks NOTE: ht is 12*divisions + 21 (see below) Uses cFrameColor, cBodyColor, cThumbColor & cTextColor from 'cctb' -------------------------------------------------------------------------------- Slider 0 any x any "Thumb" is always equal to smallest dimension 1 Scale inset 4 pixels from thumb (control rect) 2 Scale inset 8 pixels 4 scale filled with cTingeDark 8 click on scale moves thumb to that point -------------------------------------------------------------------------------- 3D Buttons 0 any x any draws a push button 1 draws a checkbox 2 draws a radiobutton 4 draws a Tog Button control 8 Use the Window font for title NOTE: This control should behave just like the standard CDEF 0 when running in 1 bit (B&W) mode OR if the background is white. If running on a non-white background, this CDEF will draw "3 D" controls. Uses cFrameColor & cTextColor from 'cctb'. Gray shading is a gray that is intermediate to the background color & cFrameColor. -------------------------------------------------------------------------------- Progress Bar 0 any x any draws a horizontal progress bar 1 draws a vertical progress bar 2 draws a rounded, 3D progress bar 4 draws a "Barber Pole" progress bar 8 not used NOTE: to get a "Barber Pole" variation to work, you need to call it with a different value each time. Simply setting min=0 and max=1, then setting its value to 0, then 1, then 0 etc. inside your loop operation will work. 'cctb' resource entries for cFillPat and cTingeLight are used to color this control. -------------------------------------------------------------------------------- TabPanel 0 20 x nn tab label is Geneva 9, bold for active tab. 1 Use System font for tab label, underline for active tab. 2 1 row of tabs, contrlMax columns. 4 not used 8 Use the Window font for tab label, bold for active tab. NOTE: To avoid problems with "layering" of this control over or under the contents of a box, set the height of this control to 16 * rows, then put the height you REALLY want in the contrlMin field of the CNTL template. The control rect (used by the Dialog Manager) will not obstruct other controls. However, when the control draws - it will use the height value from the contrlMin field. Uses cFrameColor & cTextColor from 'cctb'. Gray shading is a gray that is intermediate to the background color & cFrameColor. The default of 4 tabs per row can be changed via the LoWord of the refCon to 2 - 8. See below. -------------------------------------------------------------------------------- Non-standard control refCon usage =================================== Note: Several of these controls use the control refCon field. Strictly speaking, the refCon should be left for the caller's use, not for the CDEF. But… the Apple CDEF broke the rule and I blithely followed along (sorry). Except for the DatTime CDEF, the refCon is used only at the time the CDEF intializes, and its value is used to produce non-default behavior or appearance. If you need the refCon change the appropriate init() routine for the CDEF. PopUp Menu - use of refCon is identical to Apple's CDEF 63 - not used by control after initialization. Spinner - refCon may be used to indicate an "increment" value. Also, you can set both an increment and a DITL item (for an edit text item to update). See below. - the increment value is limited to 1-1000 and the DITL item number must be 0-100. - not used by control after initialization. VSlider - refCon may be used to indicate the number of divisions but will default to 7 divisions. Must be in the range 2-20. - not used by control after initialization. DateTime - refCon is the "value" of the control. It is updated by the control. - ** USED ** by control after initialization - see below. Tab Panel - LoWord of the refCon is "tabs per row" - from 2 to 8. If outside this range, the default is 4 tabs per row. - HiWord of the refCon is a "notch". If non-zero, there will be a notch in the the right corner with no tab, if zero, tabs will fill the entire width of the control. This value must be between 0 and control width/2. - not used by control after initialization. -------------------------------------------------------------------------------- Non-standard control template usage =================================== The Macintosh Control Manager is pretty limited in its capability for numerous control variants (just look at the popup menu CDEF!), allowing overlapping controls or passing special data to the control. I attempted to make it possible to initialize all of these controls via standard 'CNTL' templates or calls to NewControl() rather than requiring the calling program to make additional calls or use special data structures. This approach means the the meanings of some template values have been redefined as listed below: GroupBox does not use min, value or refCon. max is used for the true height of the control. Rect should be 16 pixels high, just enough for the title. PopUp Menu (see Inside Mac VI or other Docs for Apple CDEF 63) Briefly: procId : 1616 + varCode (1101 * 16) + varCode : varCodes popupFixedWidth = 0x0001 ctl3D = 0x0002 popupUseAddResMenu = 0x0004 popupUseWFont = 0x0008 value : Title justification : popupTitleLeftJust = 0x00000000 : popupTitleCenterJust = 0x00000001 : popupTitleRightJust = 0x000000FF There are also several values for setting text style for the popup title. See Inside Mac. min : resId of menu to use, even if using popupUseAddResMenu, it is best to have a 'dummy' menu resource with no items defined. max : width of title item - from controlRect.left : 0 = no title drawn. Enhancements: The following are 8 "pseudo variation codes" that can be added to the max field (title width). popupNoMark : Don't use a checkmark on current item. popupBlackSymbol : Always draw symbol in black. popupInsetFrame : Draws an inset 3D popup frame. popupSymbolOnly : Draw popup symbol for "type-in menus" popupNoSymbol : Don't draw popup symbol at all. popupCenterText : Don't draw popup symbol, don't expand control width to that of the menu and center item text in control rect. popupIconOnly : Draw item Icon in a framed box. popupNoDeleteMenu : Don't call DeleteMenu until control is disposed of. This will preserve menu color information created via calls to SetMCEntries (as opposed to those in 'mctb' resources). : use of these means that the title width must be less than 255 characters, but that seems to be a rather reasonable restriction. : popupNoMark, popupBlackSymbol and popupInsetFrame can be combined with others, but combinations of the last 4 are undefined. refCon : if varCode of popupUseAddResMenu, put the ResType in the refCon field of the control. Spinner standard use of min, max and value. The control refCon field can be set to a long word that indicates both the increment to use and a DITL item to update (optional). LOWORD = increment value (default increment is 1) HIWORD = DITL item number for an editText item to update with the control value. Date & Time max - if non-zero, reverse 12/24 hour setting. min - if non-zero, draw "3D" control. contrlValue indicates highlighted numbers 2 hours 3 minutes 4 AM/PM 7 month (7,8,9 match user order from Control Panel 8 day and may not have these meanings) 9 year contrlRfCon is seconds as passed to GetDateTime(), Secs2Date() and Date2Secs() calls. This is the "value" that the control adjusts. Use GetCRefCon() to retrieve the "date time" value and SetCRefCon() to set it. To "reset" the control (remove hilighted digits & hide arrows), simply set its value to 0 with SetControlValue. To highlight digits, set the control value to one of the values listed above. HSlider min = 0, max = 100 - these are set by the control. value returned will range from 0 to 100 VSlider refCon is used to indicate 'number of divisions' from 2-20. Default is 7 divisions with tick marks from 0-7. min = 0 max = 12*"number of divisions" The value returned will range from 0 to max. The control "thumb" will "snap" to a tick mark. This means that the value will always be 12*tick mark. To avoid the "snap" behavior, use varCode 4. 3D Buttons standard use of all fields, but with an additional variation code for "Tog" buttons. Progress Bar standard use of all fields. Control cannot be disabled. Tab Panel min = true height of the control. max = number of tabs value = "active" tab. Title is bold. title = one per tab, separated by CR (0x0d) refCon = LoWord = tabs per row (2 - 8) - default of 4 HiWord = right margin - no tabs drawn in this area. Rect should be set to #rows * 16 pixels, just enough for all rows of tabs. Control cannot be disabled. -------------------------------------------------------------------------------- Using custom controls in a dialog ================================= To use custom controls in a dialog, it is important to understand the interaction between the Dialog Manager, Control Manager and resource definitions for dialogs. Underlying all controls in a Macintosh window (dialog or other) is the Control Manager. Fundamental to this is the Toolbox call to create a new control: ControlHandle hCtl; hCtl = NewControl( theWindow, // the window the control belongs to *theRect, // rectangle for control title, // title for control visible, // initially visible or not initialValue, // control value min, // minimum value max, // maximum value ctrlType, // 16*procID+variation code refCon // user specified value ); ctrlType is an important value and an understanding of its use if key to the use of custom controls. The procID is the resource id of a code resource of type 'CDEF'. Built into the Macintosh system are 'CDEF' resources of id 0 and 1 (and others). The 'CDEF' with procID=0 is used for push buttons, check boxes and radio buttons - with variation codes of 0, 1 and 2 respectively. So, to create buttons in a window, you could use NewControl and specify: = 16*procID+variation code -------------------------- Push Button : ctrlType = 16*0+0 = 0 Check Box : ctrlType = 16*0+1 = 1 Radio Button : ctrlType = 16*0+2 = 2 A special variation code of useWindFont (8) can be used with many controls to change the font of the control. So, to use a custom control, you simply specify a procID of something other than 0. If you want to substitute a custom control (like the 3D Button CDEF) for the default CDEF id=0, include a CDEF with id=0 in your application's resource fork. This was done in the demo program (and in the xDEF.rsrc file). Items in a dialog are specified in resource description files (.r files) using a syntax unique to your resource compiler. A dialog resource is composed of a 'DLOG' resource and a corresponding 'DITL' resource. The 'DLOG' resource defines the dialog itself, while the 'DITL' resource defines the item list for the dialog. A typical item description in a 'DITL' source file might be: resource 'DITL' (128) { /* Control Rect, ctrlType, flag, title */ /* --------------------- ----------- --------- --------------- */ {249, 396, 269, 455}, Button { enabled, "OK" }, {249, 324, 269, 383}, Button { enabled, "Cancel" }, {52, 22, 68, 142}, CheckBox { enabled, "Check box" }, {76, 22, 92, 142}, RadioButton { enabled, "Radio button" } }; For some standard controls (push buttons, radio buttons etc.), there are special 'DITL' definitions, as shown above. The Dialog Manager reads the information in the 'DITL' resource, fills in some default values and calls NewControl(). (The 'enable' flag is not really a parameter to NewControl(), but sets the contrlHilite field in the control record.) This means that you don't have to fill in the entire parameter list for NewControl() to have a control in a dialog - for the standard controls. If you want to use the useWindFont variation code or a custom control in a dialog, there is some extra work to do… You must define a special type of 'DITL' item, "Control" instead of "Button" etc. and then you must provide a matching resource of type 'CNTL'. The Dialog Manager will recognize this type of 'DITL' item and read the 'CNTL' resource to get some of the parameters it will use in the call to NewControl(). The 'CNTL' resource contains fields for all of the parameters needed by NewControl(). In the example below, the DITL is changed to add the useWindFont variation to the items shown above, the resource description would look like: resource 'DITL' (128) { /* Control Rect, ctrlType, flag, 'CNTL' id */ /* --------------------- ----------- --------- --------------- */ {249, 396, 269, 455}, Control { enabled, 128 }, {249, 324, 269, 383}, Control { enabled, 129 }, {52, 22, 68, 142}, Control { enabled, 130 }, {72, 22, 88, 142}, Control { enabled, 131 } }; /* Control Rect initValue visFlag max min ctrlType refCon Title */ resource 'CNTL' (128, purgeable) { {52, 22, 68, 142}, 0, visible, 1, 0, 16*0+8, 0, "OK" }; resource 'CNTL' (130, purgeable) { {52, 22, 68, 142}, 0, visible, 1, 0, 16*0+8, 0, "Cancel" }; resource 'CNTL' (130, purgeable) { {52, 22, 68, 142}, 0, visible, 1, 0, 16*0+1+8, 0, "Check box" }; resource 'CNTL' (131, purgeable) { {72, 22, 88, 142}, 0, visible, 1, 0, 16*0+2+8, 0, "Radio button" }; ** IMPORTANT ** There are TWO rectangle definitions here - one in the 'DITL' and one in the 'CNTL'. If they don't match, your custom control may not draw, or it will flicker and seem to move when you first show the dialog. Also, clicks in the DITL rect may not be recognized by the Control when its rect is different. Make sure the rects match. If you use a resource editor instead of .r files & a resource compiler, you can define the 'DITL' and matching 'CNTL' resources directly. Resorcerer does a fine job at this. ResEdit is a bit more difficult to use. ResEdit does not keep the 2 rectangles in sync, if you drag a 'DITL' item around, the corresponding 'CNTL' is not updated. To use ResEdit, open the 'DITL' window and define a new item of type "Control" from the floating palette. Double click on the new item and fill in the resource id and rectangle information. Move this window aside, but so that you can still see the rect info. Now, hold down the command+option keys and double click on the item in the 'DITL' window. This brings up the 'CNTL' window where you can fill in the info for the 'CNTL' resource - fill in the "Bounds Rect" (top, left, bottom, right) item to match the rect in the 'DITL' window. -------------------------------------------------------------------------------- Using custom controls in a normal window ======================================== In some ways, it is easier to use a control in a normal window than in a dialog. BUT, you have to do mouseDown event processing since the Dialog Manager is not doing it for you. This is simple and identical to handling scroll bars or buttons in a window. Just call FindControl to determine where & if the mouse was clicked in a control, then call TrackControl. The code is nothing special, it looks like this: mousePt = theEvent->where; GlobalToLocal(&mousePt); partCode = FindControl(mousePt, theDialog, &controlHdl); if(partCode && controlHdl) { TrackControl(cHdl, mousePt, (ProcPtr)myTrack); } The only special things about these controls have to do with the last parameter to TrackControl - the actionProc. Normally, you can simply take the default and pass nil as the last parameter. See demoWind.c for some examples. Exceptions are: Popup Menu ---------- You must pass (ProcPtr)-1 to tell the CDEF to "autoTrack". Spinner ------- You may define an actionProc which will be called when the mouse is clicked in an arrow. Unlike a scrollBar, the Spinner CDEF will update its control value. So in your action proc, you can call GetCtlValue to obtain the current control value and do something with it (like stuff it in an edit text record or display it). Sliders ------- Sliders don't really need an actionProc, you can call TrackControl with a nil actionProc and the slider will work just fine. If you want to implement a "live" display of the value of a slider control, you simply define an actionProc, but use SetCtlAction to tell the control to call it as the "thumb" of the slider is being dragged. (You still need to call TrackControl though, or the control will not respond to clicks in the scale portion of the control). In your actionProc, you can then call GetCtlValue to obtain the control value and display it. For the rest of the CDEFs, simply call TrackControl with a nil action proc (unless you want to extract the control value and do something with it each time the mouse is clicked in the control - then you must define an actionProc). -------------------------------------------------------------------------------- Colorizing Controls & Dialogs -------------------------------------------------------------------------------- The key to having a colored dialog is to include a 'dctb' (or 'actb' for Alerts) with the same ID as the 'DLOG' or 'ALRT' resource. For controls, there is a similar resource, a 'cctb'. Either create 'cctb' resources for each 'CNTL' resource, or to color ALL controls in an application, create a 'cctb' with ID=0. For the controls that have a "3D" variant, make sure you define the cTingeLight and cTingeDark colors in your 'cctb' or you won't get a nice looking control. See demoDialog.r for examples. -------------------------------------------------------------------------------- Changing the font in a Dialog -------------------------------------------------------------------------------- Before showing your dialog (but after creating it), simple calls to: TextFont(geneva) and TextSize(9) will change the dialog font to Geneva 9. This WILL NOT WORK if you have an edit text item in the dialog or if you forget to specify the useWindFont variation for your controls. The best way to change the font for an edit item is to use 'ictb' resources, but these are a pain. Only Resorcerer does this well, Rez and ResEdit don't support 'ictb' resources. See demoDialog.c for a crude hack that seems to work. -------------------------------------------------------------------------------- Special PopUp menu notes -------------------------------------------------------------------------------- To start, the documentation in Inside Mac VI on the Apple popup menu CDEF is wrong in one detail. There is no support for "popupRightJust" as shown in figure xxx showing a title to the right of the menu. Instead, titles are always shown to the left, but can be left, center or right justified to the left of the menu. This justification is done in a "title rect" that extends from the left of the control rect for as many pixels as you specify for "title width" in the controlMax field of the control template. See the "Popup Menus" tab in the demoCDEF program to see how this works. A goal in writing this CDEF was to duplicate the Apple CDEF 63, but with one that would behave the same under System 6 and System 7 and correctly work with colored menus or on a colored background. The demoCDEF program has a dialog that shows both CDEFs side by side. I came close to calling this CDEF "yapum" (Yet Another Popup Menu) since many have posted similar code. I never found one that did exactly what I wanted (duplicate the behavior of the standard Apple CDEF), so I wrote this one. Thanks to the other writers of popup CDEFs, I learned things from your code. A major pain in writing this CDEF was insuring that the drawing of the popup when "at rest" (which is done by the CDEF) - matched EXACTLY, the drawing done by the Menu Manager when the menu is "popped up". Without this, the menu appears jerky as things shift when you click in the control. So, a goal in writing this popup CDEF was to duplicate the drawing done by the standard MDEF as closely as possible. I didn't get the drawing exactly the same in all cases. Some oddball font and size combinations may be off by a pixel or two. Also, this control has a slightly different manner of drawing the "popup symbol" and thus may be a bit wider than the Apple CDEF 63 in a few cases. It does match exactly for Chicago 12 fonts. I also deliberately centered the control title for Iconic menus rather than the Apple approach of putting the title along the top edge. IMHO, centered looks better - it is lined up with the menu item text. As far as I know, you can use this CDEF with exactly the same parameters as the Apple CDEF 63 and get the same results. (I even went as far as pasting it into my System and trying out a few apps and CommTools - it worked in most cases.) I don't recommend doing this though - Standard File was pretty much useless. There must be some special hooks in the Apple CDEF for the Folder/Disk/Desktop popup in Standard file. A minor difference is variation code 2 - this CDEF uses this for a 3D embossed title while the System 6 CDEF uses 2 to mean "use Color QD" and System 7 ignores it. I have deliberately NOT implemented 1 "feature". This CDEF will not draw command-keys. IMHO, popups should not have command key equivalents and there is a conflict when drawing - the menu manager will draw the command key equivalent where the popup must draw the "popup symbol". Apple's CDEF shifts the command key to left, but then when the menu is popped up, they shift to the right. I find this distracting. Two oddities that I have noticed are : 1). Because of the AppendDITL calls (I think), menus with icons draw the icons before drawing the popup frame. Apple's CDEF does this too, I suspect that it is a GrafPort problem but haven't really investigated. 2). If you want an menu with Icons only, no text, you have to supply a space as an item string or the standard MDEF ignores the menu. Enhancements ============ The popup CDEF in this package has several enhancements to the Apple CDEF. These extensions are NOT backward compatible with the Apple CDEF! You can see all of these extensions in the demoCDEF program on the "Popup Extensions" tab. NOTE: versions earlier than v1.3 of this CDEF used a value of -1 in the contrlMax field to indicate "popupSymbolOnly". THIS HAS BEEN CHANGED! 1). It will handle "dynamic" menus created via NewMenu() as long as you call InsertMenu() to add the menu to the menu list. 2). Variation code 2 can be used for an embossed title as with the other CDEFs in this package. This is only honored if the window background is non-white. If the "popupInsetFrame" (below) is also, the menu item text will be embossed as well. 3). There are several additional variants, all created via "pseudo variation codes" which can be combined with the control Max value - which is normally used to specify the width of the title for a popup menu. Header file jimsCDEF.h has definitions for theses extensions. The first 3 are additive and can be combined with any other "pseudo variation code". 1. No item marks (popupNoMark) Calling program can use SetItemMark() to set a mark if needed. One use of this would be to create a popup similar to the one used in Standard file dialogs. 2. Black symbol (popupBlackSymbol) Default behavior with colored menus is to draw the popup symbol in the item text color. If you always want black symbols, add this "variation code" to controlMax. 3. Inset 3D popup (popupInsetFrame) While working on the demoCDEF program, I realized that 3D dialogs (as used in the demo program) and popup menus look somewhat odd together. The standard, drop-shadowed frame of a popup has the effect of "raising" the popup above the plane of the 3D dialog. So, I added another pseudo variation code to draw the popup menu as an "inset box" - a 3D effect that has the result of placing the popup below the plane of the dialog. This only works if the dialog background color is non-white. This effect was lost if the menu background color was white as well, so I chose to use the color of the current grafPort as the background color for the menu (in the case of the demo program, red=green=blue=0xCCCC). Of course, when the menu is "popped", the standard MDEF takes over drawing and the standard menu & drop shadow appear. The following are NOT additive with each other. If added together, the results are undefined. 4. "Symbol" only popups (popupSymbolOnly) For "type in" popups often used for Font size selection in conjunction with edit text items in dialogs. Additional code is needed to implement this, see the demoCDEF program source. 5. Popups with no "Symbol" (popupNoSymbol) No downward pointing triangle is drawn, as in the System 6 version of CDEF 63. 6. Popups with icons only (popupIconOnly) This results in a "popup Icon button" effect since only a framed icon (of any size or type) is drawn. Item text and the popup symbol are not drawn. Set the control rect to 5 pixels more than the largest icon. 7. Popups with centered text (popupCenterText) This results in a "popup text button" effect since the menu item text is drawn, centered in the control rect. -------------------------------------------------------------------------------- About "TogButtons" -------------------------------------------------------------------------------- In early November 1991, I ran across an article in the October 1991 "Apple Direct" by Bruce Tognazzini - Apple's human interface guru. Each month Tog would write a column dealing with HI issues. The article that caught my eye back then was titled "Case Study: One or more Buttons". I don't think that I can legally include Tog's article with this bit of code, but you can find it on many of the Apple Developer CD's in the Periodicals:Apple Direct:Apple Direct Oct '91:Tog folder. It also is in his book "Tog on Interface" as chapter 36. To summarize, Tog wrote about the design and usability testing of a new interface element that he called "One or more Buttons" - essentially a control that was part Checkbox and part Radio button. A group of Checkboxes can all be "Off" and a group of Radio buttons can only have one "On" value. What was needed was a group that MUST have ONE "On" control but could have many "On" controls - a "One or more Button". Tog's design for what I call "Tog Buttons" is a cross between a Radio button and a Checkbox. The control is a diamond (a Checkbox rotated 90 degrees) with a diamond shaped indicator (like the circular indicator in a Radio button). The behavior is also a cross between the two other controls. If only one control is ON, then clicking on it turns that control OFF and turns on an adjacent control (just like a pair of radio buttons), if one or more of the controls is ON, then others can be toggled (just like a checkbox). Another twist on the behavior is that if only one control is ON, a click on that control will turn if OFF, and turn on the one just above (or to the left of) it. When the first (or last) control is reached, the direction reverses, turning on the one just below (or to the right). Tog likened this behavior to that of a drop of mercury when you press on it with a finger (but without the toxicity!). The behavior is such that with a single ON button, clicking on just that button, causes it to "jump" up (or leftward). If you keep chasing the single ON button, it will keep "jumping" up until it must reverse direction and start "jumping" down. Unless you are "chasing" a button like this, when only one button is ON, the default behavior is to jump UP (or to the left). To see this, try the cdefDemo program and you will see what I mean. For some reason, this appealed to me as an interesting project and I spent a fun afternoon implementing Tog's idea. I ended up creating a CDEF to implement the control described by Tog and a couple of routines in C to support the desired behavior of "Tog Buttons". -------------------------------------------------------------------------------- How to use a Tog Button in a dialog =================================== Obviously, using a Tog Button is only needed if you have a situation that has a group of items that requires "One or Many" values. An example might be a search : - Search ----------------- | | | <•> C files (.c) | | < > Include files (.h) | | < > Resource files (.r) | | | -------------------------- The file cdefDemo.c shows how to use "Tog Buttons", but here is a brief list. 1. Include the files TogLib.c/TogLib.h in your project. 2. Define the group of "Tog Buttons" in your dialog resource. 3. DITL item numbers MUST be successively numbered for each group of "Tog Buttons". This is IMPORTANT! 4. After calling GetNewDialog, but before calling ModalDialog, call initTogButtons() for each group of "Tog Buttons". 5. When a "Tog Button" is clicked, call setTogButtons() for that group of "Tog Buttons". 6. When a non-Tog Button control is clicked, do whatever is needed, then call resetTogButtons() for each group of "Tog Buttons". This step simply insures that the next click on a "Tog Button" will "go up". 7. Use regular calls to GetDItem() and GetCtlValue() to retrieve the control values for "Tog Buttons". The TogLib routines are the key to maintaining consistent behavior of the "Tog Buttons". TogLib.h has a short description of each routine. -------------------------------------------------------------------------------- About Tab Panels -------------------------------------------------------------------------------- Tab panels are what I call dialogs that use the TabPanel CDEF in this package. The CDEF is modeled after what I think is Microsoft's "Tabbed dialog" interface design. I think that this is being used in the new Mac versions of Word & Excel, but I haven't seen them yet. It could be used as an alternative to the common Mac approach of multi-panel dialogs that use a list of Icons to switch among several panels. This is doubtless a controversial interface element - even more so on the Mac. I don't condone it's use, I simply wanted to see if I could write a control like this. Think long and hard before you use this on the Mac - it may be rather foreign to Mac users and will take some thought. One of the biggest difficulties is "Where do the OK & Cancel buttons go?" and "What does a click on a tab mean?" - should changes be applied immediately, or wait for an OK on the dialog? If OK & Cancel are inside the "Tab" control, do you have to click on OK before changing tabs? How do you exit the dialog? Do you then need a "Done" button". Is a click on a tab the same as OK? and so on… If the OK and Cancel buttons are outside the "Tab" control, then do you need an "Apply" button that must be clicked or you loose changes if you switch panels by clicking on a new tab? Or is a click on a tab is that an implied acceptance of changes that will take effect when you click "OK"? There is some subtle but important stuff here. Think about it! Using the Tab Panel CDEF ------------------------ You can specify from 1 to 40 tabs with this control (one would be silly and 40 is overkill). Tabs are presented with 4 per row by default, each tab is 1/4 of the width of the control. "Tabs per row" may be between 2 and 8. If you specify a tab count that is not a multiple of "tabs per row", the remaining tabs will be wider than the others so that the entire control width is occupied. This looked better (IMHO) than having an empty space or a "dead" tab. The control max value indicates the total number of tabs. The control title should contain a title for each tab, separated by a CR. If you want to change the default number of tabs per row, put a value from 2 to 8 in the LoWord of the refCon field. If you want a "notch" on the right side with no tabs, put a "notch" value in the HiWord of the refCon field. The control rect height should be set to #rows * height of 1 tab. Then set the REAL height for the entire panel in the contrlMin field of the control template. ** NOTE ** Be particularly careful to match up the DITL item rect and CNTL rects - if these are not the same, you may end up with a "dead" row of tabs that will not respond to a click. The height of each row of tabs is calculated as : controlHeight/rows. 16 pixels per row is a good size. So, if you need 2 rows of tabs, set the control rect to be 32 high. By default, this control will use a Geneva 9 font, with the "active" tab drawn as Bold. If you use the useWindFont variation code of 8, it will use the current font. A variation code of 1 will use the System font at all times, underlined instead of bold (IMHO, this looks better than bold Chicago 12). A variation code of 2 will force a single row of tabs, with as many tabs as specified by controlMax, each as wide as controlWidth/# tabs. If the background is not white, the control will draw as a "3D" control. Please note that the control cannot be disabled, nor can a single tab be disabled. If you have a situation where an entire panel should be disabled, disable each of the controls on the panel. Changing the controls as you switch from tab to tab can be done in several ways. One is to use the AppendDITL and ShortenDITL found in System 7 - this is the approach used in the demoCDEF program and in support routines found in panelAssist.c. That file has 3 routines that might be handy - one to swap panels, one to implement command+number keys as an alternative to clicking on a tab and another to implement command+Tab or control+Tab to cycle through the tabs. If you need to use the TabPanel CDEF with System 6, a series of MoveControl or Hide/ShowControl calls would probably do the trick. The files demoDialog.c and tabDemo.c show how to use a "Tab Panel". File demoDialog.c has routines that preserve the settings of each control on each panel. File tabDemo.c is a "bare bones" example of how to work with the CDEF. Briefly, to use the TabPanel CDEF: 1. Include the files panelAssist.c/panelAssist.h in your project. 2. Define a DLOG resource and DITL that contains just 3 controls "OK", "Cancel" and the TabPanel control as items 1-3. 3. Set the contrlMax value to the number of tabs you want and provide a title for each in the control title. 4. Define a 'DITL' resource for each tab. Number them successively, starting with the previous DITL+1. 5. Study the code in demoDialog.c. That example places the OK & Cancel buttons outside the panel and saves all control values to a temp area before switching to another panel. 6. When Modal dialog informs your program that a Tab was clicked (itemHit is equal to the tabPanel DITL item), do the following: - get the value of the tab control. - save the values of other controls on the current panel. - call panelSwap with the new tab value to change panels. (this uses CountDITL, ShortenDITL and AppendDITL) - restore the values of the controls on the new panel. 7. If you want to use command+number keys to switch panels, call panelCmdKey() from your dialog filter routine whenever a keyboard event occurs with the command key down - obviously, this is only good for 10 or fewer tabs. To use command+Tab or control+Tab to rotate through tab panels, call panelCmdTab() when the control or command keys are pressed.